You are here:

Get external groups for a role

Returns external security groups used in a role

Method

/API3/access/getRoleGroups

API Section: /API3/access
API Version: 3.0
From Release: 2023.14
Usage: REST API and Client SDK libraries. REST APIs via POST actions only.
Usage by:
- Enterprise Admin

Method Signature

Input Parameters

Name

roleId

Type

string

Description

The system role ID

Output Response

Successful Result Code

200

Response List Type

ExternalGroupModel[]

Description of Response Type

External group object with details of the groups found in the role.. Note that the response is returned as a list of items of this object type.

Notes

Currently only supported in LDAP based authentications.

Examples

Create new Active Directory user (JavaScript):

This example demonstrates how to find and add a new user and roles in Pyramid, when using Active Directory authentication.

The example uses API authentication driven from JavaScript. See Authentication APIs for alternatives.

// URL of the Pyramid installation and the path to the API 3.0 REST methods
var pyramidURL = "http://mysite.com/api3/";

// step 1: authenticate admin account and get token. 
//This assumes authentication with Windows Authentication SSO. Therefore the account logging on is an admin account.
// NOTE: callApi method is a generic REST method shown below. And inside it, xhttp.withCredentials = true;
				
let token = callApi("authentication/authenticateUserWindows",{},"",false); 
log("got token "+token);

//step 2: Get the defult tenant.
let defaultTenantResult = callApi("access/getDefaultTenant",{},
token // admin token generated above
);
let tenantId = defaultTenantResult;
log("default tenant, id= "+tenantId);

//step 3: search for an active directory user in the AD itself
let searchUsers=callApi("access/searchExternalUsers",{
	"domainName":"myAdDomain",
	"searchValue":"Smith",
	"externalSearchType": 0, //search type enumeriation. 0 = exact
},token // admin token generated above
);


let adUser = searchUsers[0];
log("adUser = "+adUser.firstName);

//step 4: creating a user using the results from the search in step 3
let createUser = callApi("access/createUsersFromSearch",[
	{
	"userName": adUser.username, //using the search result from step 3 above
	"adminType": 0, //admin type
	"clientLicenseType": 100,//ClientLicenseType.Viewer
	"statusID": 1,
	"tenantId": tenantId, //tenant Id from above
	"domainName":"myAdDomain" 
}
],token );
let userId = createUser.modifiedList[0].id;
log("created user "+userId);


//step 5: optional, changing the user from Viewer to Professional
let updateUser=callApi("access/updateUsersFromSearch",[{
	"userName": adUser.username,
	"adDomainName":"myAdDomain",
	"clientLicenseType": 200,//ClientLicenseType.Professional
}],token );


//step 6: creating 2 roles
let createRole=callApi("access/createRoles",[{
	"roleName": "role1",
	"tenantId": tenantId,
	"isGroupRole": false
},{
	"roleName": "role2",
	"tenantId": tenantId,
	"isGroupRole": false
}],token);

let role1 = createRole.modifiedList[0].id;
let role2 = createRole.modifiedList[1].id;
log("created roles "+role1+","+role2);

//step 7: binding user to role1 from step 6
let addUserToRole=callApi("access/addUserToRole",{
	"userId":userId,
	"roleId":role1
},token );


//step 8: searchAdGroupsForUser, searching for AD groups of the given user in the given domain
let groups=callApi("access/searchUserGroups",{
	"domainName":"myAdDomain",
	"username":adUser.username
},token );
log("groups of " + adUser.username+" + "+JSON.stringify(groups));
let selectedGroup=groups[0];


//step 9: add role2 to the AD security group from step 8
let addRoleToAdGroup=callApi("access/updateRoleGroups",{
	roleId:"role2",
	"groupsToAdd":[{
		"domainName":selectedGroup.domainAddress,
		"groupName":selectedGroup.name
	}]
},token );
log("addRoleToAdGroup "+JSON.stringify(addRoleToAdGroup));

//step 10: optional get all groups by role - this will find the selected Group from step 9
let groupsFound=callApi("access/getRoleGroups",role2,token );
log("found group "+groupsFound[0].name);

// ##### optional generic logging method for debugging ##############
function log(msg){
	document.write(msg);
	console.log(msg);
}

// ##### generic REST API calling method ##############
function callApi(path,data,token="",parseResult=true){
	var xhttp = new XMLHttpRequest();
	
	//notice we changed callApi and added xhttp.withCredentials = true; to pass the windows credentials
	xhttp.withCredentials = true;
	
	xhttp.open("POST", pyramidURL+path, false);
	xhttp.setRequestHeader("paToken",token)
	xhttp.send(JSON.stringify(data));
	if(parseResult){
		return JSON.parse(xhttp.responseText);
	}else{
		return xhttp.responseText;
	}
}

Code Snippets

Use the Authentication API methods to generate an access 'key' or 'token' for use in code as shown below.

TypeScript

Curl

Java

Python

PHP

curl -X POST \
-H "paToken: [[apiKey]]" \
 -H "Accept: application/json,application/json;charset=utf-8,text/plain,text/plain;charset=utf-8" \
 -H "Content-Type: application/json" \
 "http://Your.Server.URL/API3/access/getRoleGroups" \
 -d ''

import com.pyramidanalytics.*;
import com.pyramidanalytics.auth.*;
import com.pyramidanalytics.model.*;
import com.pyramidanalytics.api.AccessServiceApi;

import java.util.*;
import java.time.*;

public class AccessServiceApiExample {
    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("http://Your.Server.URL/");
        
        // Configure API key authorization: paToken
        ApiKeyAuth paToken = (ApiKeyAuth) defaultClient.getAuthentication("paToken");
        paToken.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //paToken.setApiKeyPrefix("Token");

        // Create an instance of the API class
        AccessServiceApi apiInstance = new AccessServiceApi();
        // Initialize the roleId parameter object for the call
        String roleId = roleId_example; // Create the input object for the operation, type: String 

        try {
            // "array[ExternalGroupModel]" is only psaudo-code to symbolize list of type and not the actual usage 
            array[ExternalGroupModel] result = apiInstance.getRoleGroups(roleId);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling AccessServiceApi#getRoleGroups");
            e.printStackTrace();
        }
    }
}

import * as PyramidAnalyticsWebApi from "com.pyramidanalytics";

// Create an instance of the API class
const api = new PyramidAnalyticsWebApi.AccessServiceApi("http://Your.Server.URL")

// Configure API key authorization: paToken
api.setApiToken("YOUR API KEY");

const roleId = roleId_example; // {String} 

api.getRoleGroups(roleId).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});

using System;
using System.Diagnostics;
using PyramidAnalytics.Sdk.Api;
using PyramidAnalytics.Sdk.Client;
using PyramidAnalytics.Sdk.Model;

public class getRoleGroupsExample
{
    public static void Main()
    {
        Configuration conf = new Configuration();
        conf.BasePath = "http://Your.Server.URL/";
        
        
        // Configure API key authorization: paToken
        conf.ApiKey.Add("paToken", "YOUR_API_KEY");
        // Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
        // conf.ApiKeyPrefix.Add("paToken", "Bearer");

        GlobalConfiguration.Instance = conf;
        
        // Create an instance of the API class
        var apiInstance = new AccessServiceApi();
        // Initialize the roleId parameter object for the call
        var roleId = roleId_example;  // Create the input object for the operation, type: String | 

        try {
            // Returns external security groups used in a role
            // "array[ExternalGroupModel]" is only psaudo-code to symbolize array of type and not the actual usage 
            array[ExternalGroupModel] result = apiInstance.getRoleGroups(roleId);
            Debug.WriteLine(result);
        } catch (Exception e) {
            Debug.Print("Exception when calling AccessServiceApi.getRoleGroups: " + e.Message );
        }
    }
}

import com.pyramidanalytics
from com.pyramidanalytics import ApiException
from com.pyramidanalytics import AccessServiceApi
from pprint import pprint

        
# Configure API key authorization: paToken
api_config = com.pyramidanalytics.Configuration(host = 'http://Your.Server.URL/', api_key={ paToken:'YOUR_ACCESS_TOKEN' })

with com.pyramidanalytics.ApiClient(api_config) as api_client:
    # Create an instance of the API class
    api_instance = AccessServiceApi(api_client)
    # Initialize the roleId parameter object for the call
    roleId = roleId_example # String | 

    try:
        # Returns external security groups used in a role
        api_response = api_instance.get_role_groups(roleId)
        pprint(api_response)
    except ApiException as e:
        print("Exception when calling AccessServiceApi->getRoleGroups: %s\n" % e)

<?php
require_once(__DIR__ . '/vendor/autoload.php');

OpenAPITools\Client\Configuration::getDefaultConfiguration()->setHost('http://Your.Server.URL');

// Configure API key authorization: paToken
OpenAPITools\Client\Configuration::getDefaultConfiguration()->setApiKey('paToken', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// OpenAPITools\Client\Configuration::getDefaultConfiguration()->setApiKeyPrefix('paToken', 'Bearer');

// Create an instance of the API class
$api_instance = new OpenAPITools\Client\Api\AccessServiceApi();
$roleId = roleId_example; // String | 

try {
    $result = $api_instance->getRoleGroups($roleId);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling AccessServiceApi->getRoleGroups: ', $e->getMessage(), PHP_EOL;
}
?>

Feedback

Couldn't find what I was looking for

Help was confusing, unclear or incomplete

Instructions didn't work